Skip to main content

​
Overview

Loop over datasource files is an agent behavior that enables agents to iterate through files in a user’s personal knowledge base (datasource), processing each file individually. When combined with appropriate tools, the agent can automatically access and process file content without requiring manual file ID specification for each file.

​
What It Does

When this behavior is enabled, the system:
  1. Provides file context to the agent: Passes the user’s datasource file list to the agent execution
  2. Automatically adds input variables: Creates Variables.fileId, Variables.BinderID, and Variables.Path without manual configuration
  3. Automatically populates variables: Updates these variables for each file during iteration
  4. Enables sequential iteration: Processes each file in the datasource one at a time
  5. Works with compatible tools: The agent can use file retrieval tools that access the auto-populated variables

​
Quick Start - How Users Configure It

┌─────────────────────────────────────────────────────────────┐
│                    USER SETUP WORKFLOW                      │
└─────────────────────────────────────────────────────────────┘

Step 1: Enable Behavior
   │
   │ ✓ Click "Loop over datasource files" in Agent Studio
   │ ✓ Select datasource (auto-selected: UserPersonalFiles)
   │ ✓ See file count (e.g., "25 files")
   │
   ▼
Step 2: Input Variables AUTOMATICALLY Added ✨
   │
   │ ✓ Variables.fileId      (system adds this)
   │ ✓ Variables.BinderID    (system adds this)
   │ ✓ Variables.Path        (system adds this)
   │
   │ → User does NOTHING - this is automatic!
   │
   ▼
Step 3: Add Compatible Tools (Manual)
   │
   │ ✓ Add "File Content Retrieval" to model, OR
   │ ✓ Add "Binder Content Retrieval" to model, OR
   │ ✓ Add "List artifacts in Binder" to model, OR
   │ ✓ Add "List folders in Binder" to model
   │
   │ → Agent builder must manually add at least one tool
   │
   ▼
Step 4: AI Uses Auto-Populated Variables
   │
   │ During Execution (Automatic):
   │
   │ For File 1:
   │   System sets: Variables.fileId = "guid-1"
   │   AI calls: File Content Retrieval(fileId = Variables.fileId)
   │
   │ For File 2:
   │   System sets: Variables.fileId = "guid-2"
   │   AI calls: File Content Retrieval(fileId = Variables.fileId)
   │
   │ ... continues for all files ...
   │
   ▼
✓ Complete! Agent processes all files in datasource.

​
Supported Tools

The Loop over datasource files behavior works best with these tools, with agent builder configuration required:

​
1. File Content Retrieval (PRIMARY/RECOMMENDED)

  • Tool Type: FileContentRetrieval
  • Purpose: Retrieve full file content and metadata by file ID
  • API Endpoint: /v1/DataVectorSearch/file/<fileId>/content
  • Parameters:
    • fileId (string, required): The unique identifier (GUID) of the file to retrieve
  • Why it’s best: Direct file access, simple single parameter, returns complete file content
  • What it returns: Full file content, metadata, source details, and other properties

​
2. Binder Content Retrieval

  • Tool Type: BinderContentRetrieval
  • Purpose: Retrieve artifact content from a document Binder
  • API Endpoint: /index-search/v1/Binder/<BinderID>/content?path=<Path>
  • Parameters:
    • BinderID (string, required): The unique identifier of the binder
    • Path (string, required): Path to the artifact in the binder
  • What it returns: The full content of the specified artifact

​
3. List artifacts in Binder

  • Tool Type: ListBinderArtifacts
  • Purpose: Get a list of all artifacts (files) at a specific path in the Binder
  • API Endpoint: /index-search/v1/Binder/<BinderID>/files?path=<Path>
  • Parameters:
    • BinderID (string, required): The unique identifier of the binder
    • Path (string, required): Path in the binder
  • What it returns: Array of file metadata (names, paths, types, etc.)

​
4. List folders in Binder

  • Tool Type: ListBinderFolders
  • Purpose: Get a list of all folders at a specific path in the Binder
  • API Endpoint: /index-search/v1/Binder/<BinderID>/folders?path=<Path>
  • Parameters:
    • BinderID (string, required): The unique identifier of the binder
    • Path (string, required): Path in the binder
  • What it returns: Array of folder names and paths

​
How to Use (Agent Studio Instructions)

​
Complete Setup Process

Follow these steps to enable file iteration in your agent:

​
Step 1: Enable the Loop over Datasource Files Behavior

  1. Navigate to the Agent Studio
  2. Go to the Behavior section
  3. Click to enable “Loop over datasource files”
  4. Click on the Add Files in the Playground or in Catalog chat and select Look over data source files
  5. A configuration dialog will appear showing:
    • User’s personal datasource (auto-selected)
    • Datasource name (e.g., “UserPersonalFiles”)
    • Total file count (e.g., “25 files”)
  6. Click “Use datasource” to confirm
What happens: The system now knows to iterate through files in the datasource.

​
Step 2: Input Variables Are Automatically Added ✨

This is automatic! Once the behavior is enabled, the system automatically adds the following input variables for each file iteration:
VariableDescriptionAccess PatternExample Value
{{Variables.fileId}}Current file’s unique identifierUse in tool parameters or prompts"a1b2c3d4-e5f6-7890-abcd-ef1234567890"
{{Variables.BinderID}}Current binder identifierUse for Binder tools"binder-12345"
{{Variables.Path}}Current file path in binderUse for Binder tools"/documents/contracts/contract.pdf"
Key Point: You don’t need to manually create these variables. The system populates them automatically during each iteration through the files.

​
Step 3: Add Compatible Tools to Model or Canvas

This is required! You must manually add one or more of these tools:
  1. Select your Model step (AI Operation step)
  2. In the Tools section, click “Add Tool”
  3. Search for and add one of the supported tools (tools must be added to the project first):
    • “File Content Retrieval” (recommended - simplest)
    • “Binder Content Retrieval”
    • “List artifacts in Binder”
    • “List folders in Binder”
Tool Configuration:
  • The tools are now available to the AI
  • The AI can determine parameter values automatically based on the file iteration context

​
Option B: Add as Tool Step on Canvas

  1. Add a Tool Action step to your canvas
  2. Select one of the supported tools
  3. Configure parameters to either:
    • Let AI determine the values (system will use the automatically populated variables)

​
Step 4: AI Can Determine Values Automatically

The Magic: During execution, for each file in the datasource:
  1. System populates input variables: 
    Variables.fileId = "current-file-guid"
Variables.BinderID = "current-binder-id"
Variables.Path = "current-file-path"
  2. AI uses these variables to call tools: 
    File Content Retrieval(fileId = Variables.fileId)
→ Returns content of current file
  3. Process repeats for next file: 
    Variables.fileId = "next-file-guid"
Variables.BinderID = "next-binder-id"
Variables.Path = "next-file-path"

​
Summary Checklist

✅ Step 1: Enable “Loop over datasource files” behavior ✅ Step 2: Input variables automatically added (fileId, BinderID, Path) ✅ Step 3: Add File Content Retrieval or Binder tools to model/canvas ✅ Step 4: AI automatically uses populated variables for each file That’s it! The agent will now iterate through all files in the datasource.

​
Execution Flow

┌─────────────────────────────────────┐
│ Agent Studio Setup:                │
│ 1. Enables "Loop over datasource    │
│    files" behavior                  │
│ 2. Adds File Content Retrieval      │
│    tool to model/canvas             │
└──────────────┬──────────────────────┘
               │
               ▼
┌─────────────────────────────────────┐
│ User starts conversation with agent │
└──────────────┬──────────────────────┘
               │
               ▼
┌─────────────────────────────────────┐
│ Backend receives execution request  │
│ with behavior configuration:        │
│ • StoreConnectorIds: [datasource-id]│
└──────────────┬──────────────────────┘
               │
               ▼
┌─────────────────────────────────────┐
│ System identifies files in          │
│ datasource (e.g., 25 files)         │
└──────────────┬──────────────────────┘
               │
               ▼
       ┌───────────────────┐
       │ ITERATION START   │
       │ File 1 of 25      │
       └─────────┬─────────┘
                 │
                 ▼
┌─────────────────────────────────────┐
│ System AUTOMATICALLY populates      │
│ input variables:                    │
│ • Variables.fileId = "file-1-guid"  │
│ • Variables.BinderID = "binder-id-1"│
│ • Variables.Path = "/path/file1.pdf"│
└──────────────┬──────────────────────┘
               │
               ▼
┌─────────────────────────────────────┐
│ Agent execution with:               │
│ • User input                        │
│ • Populated variables (automatic)   │
│ • File Content Retrieval tool       │
└──────────────┬──────────────────────┘
               │
               ▼
┌─────────────────────────────────────┐
│ AI calls tool with current file:   │
│ File Content Retrieval(             │
│   fileId = Variables.fileId         │
│ ) → Returns file 1 content          │
└──────────────┬──────────────────────┘
               │
               ▼
┌─────────────────────────────────────┐
│ Agent processes file 1 content      │
└──────────────┬──────────────────────┘
               │
               ▼
       ┌───────────────────┐
       │ ITERATION START   │
       │ File 2 of 25      │
       └─────────┬─────────┘
                 │
                 ▼
┌─────────────────────────────────────┐
│ System AUTOMATICALLY updates        │
│ input variables:                    │
│ • Variables.fileId = "file-2-guid"  │
│ • Variables.BinderID = "binder-id-2"│
│ • Variables.Path = "/path/file2.pdf"│
└──────────────┬──────────────────────┘
               │
               ▼
┌─────────────────────────────────────┐
│ AI calls tool with next file:      │
│ File Content Retrieval(             │
│   fileId = Variables.fileId         │
│ ) → Returns file 2 content          │
└──────────────┬──────────────────────┘
               │
               ▼
        ... continues for all 25 files ...
               │
               ▼
┌─────────────────────────────────────┐
│ All files processed                 │
│ Agent compiles final response       │
└─────────────────────────────────────┘